# 内核编译与更新

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 概述

本文档介绍如何编译Quectel Pi H1的Linux内核、打包内核镜像以及更新到设备的完整流程。Quectel Pi H1使用基于Yocto的构建系统，采用Qualcomm定制的Linux内核（基于Linux 6.6）。

# 内核Recipes说明

Qualcomm Linux的内核recipes位于 */layers/meta-qcom-hwe/recipes-kernel/linux* 目录，该层提供两种内核方案：

| **Recipes文件** | **内核类型** | **源码来源** | **说明** |
| --- | --- | --- | --- |
| linux-qcom-custom_6.6.bb | Custom BSP | git.codelinaro.org | 高通定制内核（当前使用） |
| linux-qcom-base_6.6.bb | Base BSP | git.kernel.org | 标准内核 |

> **当前使用**：Custom内核源码方案

# 目录结构

内核相关文件主要分为两个目录：

```plaintext
qcm6490-idp/
├── kernel-source/               # 内核源码目录
└── kernel-build-artifacts/      # 构建产物目录
```

## kernel-source/目录

存放Linux内核的完整源码，包括：

- 内核核心代码（*arch/*, *drivers/*, *fs/*, *net/* 等）

- 设备树源文件（*.dts*/*.dtsi*，描述硬件配置）

- 内核配置文件（*Kconfig*）

- 编译脚本（*Makefile*）

### 源码目录详解

```{image} images/image_Sa9Mb0LrqoC0P8xM725cz6E8n0g.webp
:width: 1238px
:height: 59px
```

| **目录/文件** | **说明** | **目录/文件** | **说明** |
| --- | --- | --- | --- |
| arch | 架构相关代码（ARM64、x86等） | scripts | 编译和配置脚本 |
| block | 块设备子系统 | security | 安全框架（SELinux、AppArmor等） |
| certs | 内核证书和签名 | sound | 音频子系统（ALSA） |
| crypto | 加密API和算法 | tools | 内核相关工具 |
| Documentation | 内核文档 | usr | initramfs生成相关 |
| drivers | 设备驱动程序 | virt | 虚拟化支持（KVM） |
| fs | 文件系统实现 | rust | Rust语言支持 |
| include | 内核头文件 | Makefile | 主编译文件 |
| init | 内核初始化代码 | Kbuild | 内核构建系统配置 |
| ipc | 进程间通信机制 | Kconfig | 内核配置界面定义 |
| kernel | 内核核心功能（调度器、进程管理等） | MAINTAINERS | 维护者名单 |
| lib | 通用库函数 | CREDITS | 贡献者列表 |
| mm | 内存管理子系统 | COPYING | 版权声明（GPL） |
| net | 网络协议栈 |   |   |
| samples | 内核编程示例代码 |   |   |

## kernel-build-artifacts/目录

存放内核编译后的构建产物，包括：

- **内核镜像文件**：*Image*（未压缩）或 *Image.gz*（压缩版）

- **设备树二进制文件**：*.dtb* 文件（由 *.dts* 编译生成）

- **内核模块**：*.ko* 文件（可加载的驱动模块）

- **配置文件**：*.config*、*build.log* 等

# 编译内核

## 配置编译环境

进入代码工作目录，执行以下命令配置编译环境：

```bash
source quectel_build/compile/build.sh
```

## 执行编译

使用Yocto的 *bitbake* 命令编译内核：

```bash
bitbake linux-qcom-custom
```

## 构建产物路径

编译完成后，内核镜像生成在以下位置：

**临时工作目录**：

```plaintext
build-qcom-wayland/tmp-glibc/work/qcm6490_idp-qcom-linux/linux-qcom-custom/6.6/deploy-linux-qcom-custom
```

**最终部署目录**（Yocto自动复制）：

```plaintext
build-qcom-wayland/tmp-glibc/deploy/images/qcm6490-idp/
```

```{image} images/image_Wj6HbnGxcoG6XcxXJjhcE9SynUc.webp
:width: 1362px
:height: 108px
```

> **说明**：Yocto会自动将内核镜像从工作目录复制到部署目录，后续打包流程会从部署目录获取内核镜像。

## 编译时间参考

- **首次编译**：约30~60分钟（取决于硬件配置）

- **增量编译**：约5~15分钟

# 打包内核和设备树镜像

## 安装ukify工具

首先安装打包所需的Python依赖：

```bash
sudo pip install pefile
```

## 执行打包命令

运行以下命令打包内核镜像和设备树：

```bash
do_kernel_images
```

## ukify警告说明

执行打包过程中，会出现以下警告信息，**可以忽略**：

```bash
Kernel version not specified, starting autodetection .
Real-Mode Kernel Header magic not found
+ readelf --notes {TOPDIR}/quectel_build/alpha/tools/pack/image_temp/Image
readelf: Error: Not an ELF file - it has the wrong magic bytes at the start
Found uname version: 6.6.52-qli-1.3-ver.1.1
Wrote unsigned ${TOPDIR}/quectel_build/alpha/tools/pack/image_temp/uki.efi
```

> **说明**：这些警告是由于ARM64内核格式与EFI工具预期格式的差异导致，不影响最终镜像的正确性。

## 获取打包镜像

打包完成后，从以下路径获取生成的镜像文件：

```plaintext
${TOPDIR}/quectel_build/alpha/output/pack/efi.bin
```

# 更新镜像到设备

## 方法一：通过调试串口进入Fastboot

### 进入Fastboot模式

**选项A -通过串口命令**：

连接调试串口，在系统中执行：

```bash
reboot bootloader
```

**选项B -通过ADB命令**：

确保设备已连接USB并启用ADB调试，执行：

```bash
adb shell
reboot bootloader
```

### 验证Fastboot模式

设备进入Fastboot模式后，在主机上运行：

```bash
fastboot devices
```

应该能看到设备列表。

### 烧写内核镜像

使用fastboot命令烧写新的内核镜像：

```bash
fastboot flash efi efi.bin
```

### 重启设备

烧写完成后，重启设备：

```bash
fastboot reboot
```

## 方法二：自动化脚本（可选）

如果需要频繁更新内核，可以创建自动化脚本：

```bash
#!/bin/bash# update_kernel.sh# 检查efi.bin是否存在if [ ! -f "quectel_build/alpha/output/pack/efi.bin" ]; thenecho "错误：efi.bin 不存在，请先编译和打包内核"exit 1fi# 进入Fastboot
adb reboot bootloader
sleep 5# 等待Fastboot就绪
fastboot devices

# 烧写镜像
fastboot flash efi quectel_build/alpha/output/pack/efi.bin

# 重启
fastboot rebootecho "内核更新完成！"
```

使用方法：

```bash
chmod +x update_kernel.sh
./update_kernel.sh
```

# 注意事项

1. **备份重要数据**：更新内核前请确保重要数据已备份

2. **电源充足**：烧写过程中请确保设备电量充足或连接电源

3. **USB连接稳定**：使用质量好的USB线缆，避免烧写中断

4. **版本匹配**：确保内核版本与系统其他组件兼容

# 常见问题

## Q1: bitbake编译失败？

**可能原因**：

- 磁盘空间不足

- 网络连接问题

- 依赖包缺失

**解决方法**：

```bash
# 清理编译缓存
bitbake -c cleanall linux-qcom-custom
# 重新编译
bitbake linux-qcom-custom
```

## Q2: 验证Fastboot模式后仍看不到设备？

**解决方法**：

- 检查USB驱动是否正确安装

- 尝试更换USB端口或线缆

- 确认设备已正确进入Fastboot模式（屏幕显示Fastboot字样）

## Q3: 烧写后无法启动？

**解决方法**：

- 使用原厂镜像恢复系统

- 检查编译过程是否有错误

- 确认设备树配置是否正确

# 相关文档

- [设备树文件说明](<../设备树文件说明/设备树文件说明.md>)

- [交叉编译工具链](<../交叉编译工具链/交叉编译工具链.md>)